TeX 1995 July

home *** CD-ROM | disk | FTP | other *** search

/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / eplain / doc / eplain.info-1 (.txt) < prev next >

Wrap

GNU Info File | 1994-05-01 | 49KB | 911 lines

This is Info file eplain.info, produced by Makeinfo-1.55 from the input file eplain.texi. This file documents the Eplain macros. Copyright (C) 1989, 90, 91, 92, 93, 94 Karl Berry. Steven Smith wrote the documentation for the commutative diagram macros. (He also wrote the macros.) Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English. File: eplain.info, Node: Top, Next: Introduction, Prev: (DIR), Up: (DIR) Eplain ****** The Eplain macros provide functionality that is intended to be useful regardless of how your document is actually formatted. This manual is for Eplain version 2.6. * Menu: * Introduction:: Eplain's purpose and philosophy. * Installation:: How to install Eplain. * Invoking Eplain:: * User definitions:: Macros to be used in a document. * Arrow theoretic diagrams:: Macros for commutative diagrams. * Programming definitions:: Macros to be used in writing other macros. * Copying:: * Freedom:: * Macro index:: Entries for TeX and Eplain control sequences. * Concept index:: General index. -- The Detailed Node Listing -- User definitions * Diagnostics:: Tracing information. * Rules:: Changing the default rule dimensions. * Citations:: Using BibTeX and Eplain to make bibliographies. * Displays:: Changing the formatting of math displays. * Time of day:: Producing the time of day. * Lists:: Producing numbered and unordered lists. * Verbatim listing:: Producing text just as it appears. * Contents:: Making a table of contents. * Cross-references:: Symbolically referring to pages or equations. * Page references:: * Justification:: Left- or right-justification, or centering. * Tables:: Producing ordered tables. * Margins:: Changing the margins directly. * Multiple columns:: Getting output in two columns. * Footnotes:: Autonumbered footnotes; changing formatting. * Fractions:: A better way to produce fractions in text. * Paths:: Allowing line breaks in pathnames. * Logos:: Various logos. * Boxes:: Producing filled or open rectangles. Citations * Formatting citations:: Changing the way citations are printed. * Formatting bibliographies:: Changing the way bibliographies are printed. Displays * Formatting displays:: General formatting of displays. Lists * Formatting lists:: Changing how the lists look. Cross-references * Defining generic references:: * Using generic references:: Page references * Equation references:: Equation references * Formatting equation references:: * Subequation references:: Arrow theoretic diagrams * Slanted lines and vectors:: * Commutative diagrams:: Commutative diagrams * Arrows and morphisms:: * Construction of commutative diagrams:: * Commutative diagram parameters:: Programming definitions * Category codes:: Changing category codes. * Allocation macros:: Non-outer versions of \newcount et al. * Iteration:: Doing `for' loops in TeX. * Macro arguments:: Reading and ignoring them. * Converting to characters:: Normalizing control sequences and spaces. * Expansion:: Controlling expansion. * Obeying spaces:: Making whitespace count anywhere. * Writing out numbers:: Making `1' into `one'. * Mode-specific penalties:: * Auxiliary files:: Testing for their existence. Expansion * \csn and \ece:: * \edefappend:: * Hooks:: Manipulating and executing named actions. * Properties:: Associating information with a csname. * \expandonce:: * \ifundefined:: * \futurenonspacelet:: Regain your programming freedom * Software patents:: Algorithm monopolies. * User interface copyright:: Forbidding upward-compatibility. * What to do?:: File: eplain.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top Introduction ************ The "Eplain" macro package expands on and extends the definitions in plain TeX. This manual describes the definitions that you, as either an author or a macro writer, might like to use. It doesn't discuss the implementation; see comments in the source code (`xeplain.tex') for that. Eplain is not intended to provide "generic typesetting capabilities, as do LaTeX (written by Leslie Lamport) or Texinfo (written by Richard Stallman and others). Instead, it provides definitions that are intended to be useful regardless of the high-level commands that you use when you actually prepare your manuscript. For example, Eplain does not have a command `\section', which would format section headings in an "appropriate" way, such as LaTeX's `\section'. The philosophy of Eplain is that some people will always need or want to go beyond the macro designer's idea of "appropriate". Such canned macros are fine--as long as you are willing to accept the resulting output. If you don't like the results, or if you are trying to match a different format, you are out of luck. On the other hand, almost everyone would like capabilities such as cross-referencing by labels, so that you don't have to put actual page numbers in the manuscript. The author of Eplain is not aware of any generally available macro packages that (1) do not force their typographic style on an author, and yet (2) provide such capabilities. Besides such generic macros as cross-referencing, Eplain contains another set of definitions: ones that change the conventions of plain TeX's output. For example, math displays in TeX are, by default, centered. If you want your displays to come out left-justified, you have to plow through `The TeXbook' to find some way to do it, and then adapt the code to your own needs. Eplain tries to take care of the messy details of such things, while still leaving the detailed appearance of the output up to you. Finally, numerous definitions turned out to be useful as Eplain was developed. They are also documented in this manual, on the chance that people writing other macros will be able to use them. You can send bug reports or suggestions to tex-eplain@cs.umb.edu. The current version number of Eplain is defined as the macro `\fmtversion' at the end of the source file `eplain.tex'. When corresponding, please refer to it. To get on this mailing list yourself, email `tex-eplain-request@cs.umb.edu' with a message whose body contains a subscribe YOU@YOUR.PREFERRED.ADDRESS File: eplain.info, Node: Installation, Next: Invoking Eplain, Prev: Introduction, Up: Top Installation ************ The simplest way to install Eplain is simply to install the file `eplain.tex' in a directory where TeX will find it. What that directory is obviously depends on your operating system and TeX installation. I personally install `eplain.tex' in a directory `/usr/local/lib/texmf/tex/plain'. If you want, you can also create a format (`.fmt') file for Eplain, which will eliminate the time spent reading the macro source file with `\input'. You do this by issuing a sequence of Unix commands something like this: prompt$ touch eplain.aux prompt$ initex This is TeX, ... **&plain eplain (eplain.tex) *\dump ... MESSAGES ... You must make sure that `eplain.aux' exists *before* you run `initex'; otherwise, warning messages about undefined labels will never be issued. You then have to install the resulting `eplain.fmt' in some system directory or set an environment variable to tell TeX how to find it. I install the format files in `/usr/local/lib/texmf/ini'; the environment variable for the Web2C port of TeX to Unix is `TEXFORMATS'. Some implementations of TeX (including Web2C) use the name by which TeX is invoked to determine what format to read. For them, you should make a link to the `virtex' program named `etex', and then install the format file with the name `etex.fmt'. This lets users invoke TeX as `etex' and get the format file read automatically, without having to say `&eplain'. For convenience, the file `etex.tex' in the distribution directory does `\input eplain' and then `\dump', so that if you replace `eplain' with `etex' in the example above, the format file will end up with the right name. The `install' target in the `Makefile' does all this properly for Unix systems and Web2C. You may have to change the pathnames. Under emtex, `eaj@acpub.duke.edu' says that tex386 -i ^&plain eplain \dump produces a format file. File: eplain.info, Node: Invoking Eplain, Next: User definitions, Prev: Installation, Up: Top Invoking Eplain *************** The simplest way to use Eplain is simply to put: \input eplain at the beginning of your input file. The macro file is small enough that reading it does not take an unbearably long time--at least on contemporary machines. In addition, if a format (`.fmt') file has been created for Eplain (see the previous section), you can eliminate the time spent reading the macro source file. You do this by responding `&eplain' or `&etex' to TeX's `**' prompt. For example: initex This is TeX, ... **&eplain myfile Depending on the implementation of TeX which you are using, you might also be able to invoke TeX as `etex' and have the format file automatically read. If you write something which you will be distributing to others, you won't know if the Eplain format will be loaded already. If it is, then doing `\input eplain' will waste time; if it isn't, then you must load it. To solve this, Eplain defines the control sequence `\eplain' to be the letter `t' (a convention borrowed from Lisp; it doesn't actually matter what the definition is, only that the definition exists). Therefore, you can do the following: \ifx\eplain\undefined \input eplain \fi where `\undefined' must never acquire a definition. Eplain consists of several source files: `xeplain.tex' most of the macros; `arrow.tex' commutative diagram macros, *note Arrow theoretic diagrams::. (written by Steven Smith); `btxmac.tex' bibliography-related macros, *note Citations::.; `texnames.sty' abbreviations for various TeX-related names, *note Logos::. (edited by Nelson Beebe). The file `eplain.tex' is all of these files merged together, with comments removed. All of these files except `xeplain.tex' can be input individually, if all you want are the definitions in that file. Also, since the bibliography macros are fairly extensive, you might not want to load them, to conserve TeX's memory. Therefore, if the control sequence `\nobibtex' is defined, then the bibliography definitions are skipped. You must set `\nobibtex' before `eplain.tex' is read, naturally. For example, you could start your input file like this: \let\nobibtex = t \input eplain By default, `\nobibtex' is undefined, and so the bibliography definitions *are* made. Likewise, define `\noarrow' if you don't want to include the commutative diagram macros from `arrow.tex', perhaps because you already have conflicting ones. If you don't want to read or write an `aux' file at all, for any kind of cross-referencing, define `\noauxfile' before reading `eplain.tex'. This also turns off all warnings about undefined labels. Eplain conflicts with AMSTeX (more precisely, with `amsppt.sty') The macros `\cite' and `\ref' are defined by both. If you want to use AMSTeX's `\cite', the solution is to define `\nobibtex' before reading Eplain, as described above. If you have `amsppt.sty' loaded and use `\ref', Eplain writes a warning on your terminal. If you want to use the AMSTeX `\ref', do `\let\ref = \amsref' after reading Eplain. To avoid the warning, do `\let\ref = \eplainref' after reading Eplain and before using `\ref'. File: eplain.info, Node: User definitions, Next: Arrow theoretic diagrams, Prev: Invoking Eplain, Up: Top User definitions **************** This chapter describes definitions that are meant to be used directly in a document. When appropriate, ways to change the default formatting are described in subsections. * Menu: * Diagnostics:: Tracing information. * Rules:: Changing the default rule dimensions. * Citations:: Using BibTeX and Eplain to make bibliographies. * Displays:: Changing the formatting of math displays. * Time of day:: Producing the time of day. * Lists:: Producing numbered and unordered lists. * Verbatim listing:: Producing text just as it appears. * Contents:: Making a table of contents. * Cross-references:: Symbolic references to equations, figures, etc. * Page references:: Symbolic references to page numbers. * Indexing:: Creating and typesetting indexes. * Justification:: Left- or right-justification by lines, or centering. * Tables:: Producing ordered tables. * Margins:: Changing the margins directly. * Multiple columns:: Getting output in two columns. * Footnotes:: Autonumbered footnotes; changing formatting. * Fractions:: A better way to produce fractions in text. * Paths:: Allowing line breaks in pathnames. * Logos:: Various logos. * Boxes:: Producing filled or open rectangles. File: eplain.info, Node: Diagnostics, Next: Rules, Up: User definitions Diagnostics =========== Plain TeX provides the `\tracingall' command, to turn on the maximum amount of tracing possible in TeX. The (usually voluminous) output from `\tracingall' goes both on the terminal and into the transcript file. It is sometimes easier to have the output go only to the transcript file, so you can peruse it at your leisure and not obscure other output to the terminal. So, Eplain provides the command `\loggingall'. (For some reason, this command is available in Metafont, but not in TeX.) It is also sometimes useful to see the complete contents of boxes. `\tracingboxes' does this. (It doesn't affect whether or not the contents are shown on the terminal.) You can turn off all tracing with `\tracingoff'. You can also turn logging on and off globally, so you don't have to worry about whether or not you're inside a group at the time of command. These variants are named `\gloggingall' and `\gtracingall'. Finally, if you write your own help messages (see `\newhelp' in `The TeXbook'), you want a convenient way to break lines in them. This is what TeX's `\newlinechar' parameter is for; however, plain TeX doesn't set `\newlinechar'. Therefore, Eplain defines it to be the character `^^J'. For example, one of Eplain's own error messages is defined as follows: \newhelp\envhelp{Perhaps you forgot to end the previous^^J% environment? I'm finishing off the current group,^^J% hoping that will fix it.}% File: eplain.info, Node: Rules, Next: Citations, Prev: Diagnostics, Up: User definitions Rules ===== The default dimensions of rules are defined in chapter 21 of the `The TeXbook'. To sum up what is given there, the "thickness" of rules is 0.4pt by default. Eplain defines three parameters that let you change this dimension: `\hruledefaultheight', `\hruledefaultdepth', and `\vruledefaultwidth'. By default, they are defined as `The TeXbook' describes. But it would be wrong to redefine `\hrule' and `\vrule'. For one thing, some macros in plain TeX depend on the default dimensions being used; for another, rules are used quite heavily, and the performance impact of making it a macro can be noticeable. Therefore, to take advantage of the default rule parameters, you must use `\ehrule' and `\evrule'. File: eplain.info, Node: Citations, Next: Displays, Prev: Rules, Up: User definitions Citations ========= Bibliographies are part of almost every technical document. To handle them easily, you need two things: a program to do the tedious formatting, and a way to cite references by labels, rather than by numbers. The BibTeX program, written by Oren Patashnik, takes care of the first item; the citation commands in LaTeX, written to be used with BibTeX, take care of the second. Therefore, Eplain adopts the use of BibTeX, and virtually the same interface as LaTeX. The general idea is that you put citation commands in the text of your document, and commands saying where the bibliography data is. When you run TeX, these commands produce output on the file with the same root name as your document (by default) and the extension `.aux'. BibTeX reads this file. You should put the bibliography data in a file or files with the extension `.bib'. BibTeX writes out a file with the same root name as your document and extension `.bbl'. Eplain reads this file the next time you run your document through TeX. (It takes multiple passes to get everything straight, because usually after seeing your bibliography typeset, you want to make changes in the `.bib' file, which means you have to run BibTeX again, which means you have to run TeX again...) An annotated example of the whole process is given below. If your document has more than one bibliography--for example, if it is a collection of papers--you can tell Eplain to use a different root name for the `.bbl' file by defining the control sequence `\bblfilebasename'. The default definition is simply `\jobname'. See the document `BibTeXing' (whose text is in the file `btxdoc.tex', which should be in the Eplain distribution you got) for information on how to write your .bib files. Both the BibTeX and the Eplain distributions contain several examples, also. The `\cite' command produces a citation in the text of your document. The exact printed form the citation will take is under your control; *note Formatting citations::.. `\cite' takes one required argument, a comma-separated list of cross-reference labels (*note Cross-references::., for exactly what characters are allowed in such labels). Warning: spaces in this list are taken as part of the following label name, which is probably not what you expect. The `\cite' command also produces a command in the .aux file that tells BibTeX to retrieve the given reference(s) from the .bib file. `\cite' also takes one optional argument, which you specify within square brackets, as in LaTeX. This text is simply typeset after the citations. (See the example below.) Another command, `\nocite', puts the given reference(s) into the bibliography, but produces nothing in the text. The `\bibliography' command is next. It serves two purposes: producing the typeset bibliography, and telling BibTeX the root names of the .bib files. Therefore, the argument to `\bibliography' is a comma separated list of the .bib files (without the `.bib'). Again, spaces in this list are significant. You tell BibTeX the particular style in which you want your bibliography typeset with one more command: `\bibliographystyle'. The argument to this is a single filename STYLE, which tells BibTeX to look for a file STYLE.bst. See the document `Designing BibTeX styles' (whose text is in the `btxhak.tex') for information on how to write your own styles. Eplain automatically reads the citations from the .aux file when your job starts. If you don't want to see the messages about undefined citations, you can say `\xrefwarningfalse' before making any citations. Eplain automatically does this if the .aux file does not exist. You can restore the default by saying `\xrefwarningtrue'. Here is a TeX input file that illustrates the various commands. \input eplain % Reads the .aux file. Two citations to Knuthian works: \cite[note]{surreal,concrete-math}. \beginsection{References.}\par % Title for the bibliography. \bibliography{knuth} % Use knuth.bib for the labels. \bibliographystyle{plain} % Number the references. \end % End of the document. If we suppose that this file was named `citex.tex' and that the bibliography data is in `knuth.bib' (as the `\bibliography' command says), the following commands do what's required. (`$ ' represents the shell prompt.) $ tex citex (produces undefined citation messages) $ bibtex citex (read knuth.bib and citex.aux, write citex.bbl) $ tex citex (read citex.bbl, still have undefined citations) $ tex citex (one more time, to resolve the references) The output looks something like (because we used the plain bibliography style): Two citations to Knuthian works: [2,1 note]. References [1] Ronald L. Graham, Donald E. Knuth, and Oren Patashnik. Concrete Mathematics. Addison-Wesley, Reading, Massachusetts, 1989. [2] Donald E. Knuth. Surreal Numbers. Addison-Wesley, Reading, Massachusetts, 1974. See the BibTeX documentation for information on how to write the bibliography databases, and the bibliography styles that are available. (If you want your references printed with names, as in [Knu74], instead of numbered, the bibliography style is `alpha'.) * Menu: * Formatting citations:: Changing the way citations are printed. * Formatting bibliographies:: Changing the way bibliographies are printed. File: eplain.info, Node: Formatting citations, Next: Formatting bibliographies, Up: Citations Formatting citations -------------------- You may wish to change Eplain's formatting of citations; i.e., the result of your `\cite' commands. By default, the citation labels are printed one after another, separated by commas and enclosed in brackets, using the main text font. Some formats require other styles, such as superscripted labels. You can accomodate such formats by redefining the following macros. `\printcitestart' `\printcitefinish' Eplain expands these macros at the begining and end of the list of citations for each `\cite' command. By default, they produce a `[' and `]', respectively. `\printbetweencitations' If a `\cite' command has multiple citations, as in `\cite{acp,texbook}', Eplain expands this macro in between each pair of citations. By default, it produces a comma followed by a space. `\printcitenote' This macro takes one argument, which is the optional note to the `\cite' command. If the `\cite' command had no note, this macro isn't used. Otherwise, it should print the note. By default, the note is preceded with a comma and a space. Here is an example, showing you could produce citations as superscripted labels, with the optional notes in parentheses. \def\printcitestart{\unskip $^\bgroup} \def\printbetweencitations{,} \def\printcitefinish{\egroup$} \def\printcitenote#1{\hbox{\sevenrm\space (#1)}} File: eplain.info, Node: Formatting bibliographies, Prev: Formatting citations, Up: Citations Formatting bibliographies ------------------------- You may wish to change Eplain's formatting of the bibliography, especially with respect to the fonts that are used. Therefore, Eplain provides the following control sequences: `\biblabelwidth' This control sequence represents a `\dimen' register, and its value is the width of the widest label in the bibliography. Although it is unlikely you will ever want to redefine it, you might want to use it if you redefine `\biblabelprint', below. `\biblabelprint' This macro takes one argument, the label to print. By default, the label is put in a box of width `\biblabelwidth', and is followed by an enspace. When you want to change the spacing around the labels, this is the right macro to redefine. `\biblabelcontents' This macro also takes one argument, the label to print. By default, the label is printed using the font `\bblrm' (below), and enclosed in brackets. When you want to change the appearance of the label, but not the spacing around it, this is the right macro to redefine. `\bblrm' The default font used for printing the bibliography. `\bblem' The font used for printing the titles and other "emphasized" material. `\bblsc' In some styles, authors' names are printed in a caps-and-small-caps font. In those cases, this font is used. `\bblnewblock' This is invoked between each of the parts of a bibliography entry. The default is to leave some extra space between the parts; you could redefine it to start each part on a new line (for example). A part is simply a main element of the entry; for example, the author is a part. (It was LaTeX that introduced the (misleading, as far as I am concerned) term `block' for this.) `\biblabelextraspace' Bibliography entries are typeset with a hanging indentation of `\biblabelwidth' plus this. The default is `.5em', where the em width is taken from the `\bblrm' font. If you want to change this, you should do it inside `\bblhook'. `\bblhook' This is expanded before reading the .bbl file. By default, it does nothing. You could, for example, define it to set the bibliography fonts, or produce the heading for the references. Two spacing parameters must be changed inside `\bblhook': `\parskip', which produces extra space between the items; and `\biblabelextraspace', which is described above. (By the way, `\hookappend' won't work with `\bblhook', despite the names. Just use `\def'.) If you are really desperate, you can also hand-edit the .bbl file that BibTeX produces to do anything you wish. File: eplain.info, Node: Displays, Next: Time of day, Prev: Citations, Up: User definitions Displays ======== By default, TeX centers displayed material. (Displayed material is just whatever you put between `$$''s--it's not necessarily mathematics.) Many layouts would be better served if the displayed material was left-justified. Therefore, Eplain provides the command `\leftdisplays', which indents displayed material by `\parindent' plus `\leftskip', plus `\leftdisplayindent'. You can go back to centering displays with `\centereddisplays'. (It is usually poor typography to have both centered and left-justified displays in a single publication, though.) `\leftdisplays' also changes the plain TeX commands that deal with alignments inside math displays, `\displaylines', `\eqalignno', and `\leqalignno', to produce left-justified text. You can still override this formatting by inserting `\hfill' glue, as explained in `The TeXbook'. * Menu: * Formatting displays:: General formatting of displays. File: eplain.info, Node: Formatting displays, Up: Displays Formatting displays ------------------- If you want some other kind of formatting, you can write a definition of your own, analogous to `\leftdisplays'. You need only make sure that `\leftdisplaysetup' is called at the beginning of every display (presumably by invoking it in TeX's `\everydisplay' parameter), and to define `\generaldisplay'. `\leftdisplays' expands the old value of `\everydisplay' before calling `\leftdisplaysetup', so that any changes you have made to it won't be lost. That old token list as available as the value of the token register `\previouseverydisplay'. File: eplain.info, Node: Time of day, Next: Lists, Prev: Displays, Up: User definitions Time of day =========== TeX provides the day, month, and year as numeric quantities (unless your TeX implementation is woefully deficient). Eplain provides some control sequences to make them a little more friendly to humans. `\monthname' produces the name of the current month, abbreviated to three letters. `\fullmonthname' produces the name of the current month, unabbreviated (in English). `\timestring' produces the current time, as in `1:14 p.m.' `\timestamp' produces the current date and time, as in `23 Apr 64 1:14 p.m.'. (Except the spacing is slightly different.) `\today' produces the current date, as in `23 April 1964'. File: eplain.info, Node: Lists, Next: Verbatim listing, Prev: Time of day, Up: User definitions Lists ===== Many documents require lists of items, either numbered or simply enumerated. Plain TeX defines one macro to help with creating lists, `\item', but that is insufficient in many cases. Therefore, Eplain provides two pairs of commands: `\numberedlist ... \endnumberedlist' `\orderedlist ... \endorderedlist' These commands (they are synonyms) produce a list with the items numbered sequentially, starting from one. A nested `\numberedlist' labels the items with lowercase letters, starting with `a'. Another nested `\numberedlist' labels the items with roman numerals. Yet more deeply nested numbered lists label items with `*'. `\unorderedlist ... \endunorderedlist' This produces a list with the items labelled with small black boxes ("square bullets"). A nested `\unorderedlist' labels items with em-dashes. Doubly (and deeper) nested unordered lists label items with `*'s. The two kinds of lists can be nested within each other, as well. In both kinds of lists, you begin an item with `\li'. An item may continue for several paragraphs. Each item starts a paragraph. You can give `\li' an optional argument, a cross-reference label. It's defined to be the "marker" for the current item. This is useful if the list items are numbered. You can produce the value of the label with `\xrefn'. *Note Cross-references::. You can also say `\listcompact' right after `\numberedlist' or `\unorderedlist'. The items in the list will then not have any extra space between them (*note Formatting lists::.). You might want to do this if the items in this particular list are short. Here is an example: \numberedlist\listcompact \li The first item. \li The second item. The second paragraph of the second item. \endnumberedlist * Menu: * Formatting lists:: Changing how the lists look. File: eplain.info, Node: Formatting lists, Up: Lists Formatting lists ---------------- Several registers define the spacing associated with lists. It is likely that their default values won't suit your particular layout. `\abovelistskipamount, \belowlistskipamount' The vertical glue inserted before and after every list, respectively. `\interitemskipamount' The vertical glue inserted before each item except the first. `\listcompact' resets this to zero, as mentioned above. `\listleftindent, \listrightindent' `\listrightindent' is the amount of space by which the list is indented on the right; i.e., it is added to `\rightskip'. `\listleftindent' is the amount of space, *relative to* `\parindent', by which the list is indented on the left. Why treat the two parameters differently? Because (a) it is more useful to make the list indentation depend on the paragraph indentation; (b) footnotes aren't formatted right if `\parindent' is reset to zero. The three vertical glues are inserted by macros, and preceded by penalties: `\abovelistskip' does `\vpenalty\abovelistpenalty' and then `\vskip\abovelistskip'. `\belowlistskip' and `\interitemskip' are analogous. In addition, the macro `\listmarkerspace' is called to separate the item label from the item text. This is set to `\enspace' by default. If you want to change the labels on the items, you can redefine these macros: `\numberedmarker' or `\unorderedmarker'. The following registers might be useful if you do: `\numberedlistdepth, \unorderedlistdepth' These keep track of the depth of nesting of the two kinds of lists. `\itemnumber, \itemletter' These keep track of the number of items that have been seen in the current numbered list. They are both integer registers. The difference is that `\itemnumber' starts at one, and `\itemletter' starts at 97, i.e., lowercase `a'. You can also redefine the control sequences that are used internally, if you want to do something radically different: `\beginlist' is invoked to begin both kinds of lists; `\printitem' is invoked to print the label (and space following the label) for each item; and `\endlist' is invoked to end both kinds of lists. File: eplain.info, Node: Verbatim listing, Next: Contents, Prev: Lists, Up: User definitions Verbatim listing ================ It is sometimes useful to include a file verbatim in your document; for example, part of a computer program. The `\listing' command is given one argument, a filename, and produces the contents of that file in your document. `\listing' expands `\listingfont' to set the current font. The default value of `\listingfont' is `\tt'. You can take arbitrary actions before reading the file by defining the macro `\setuplistinghook'. This is expanded just before the file is input. If you want to have line numbers on the output, you can say `\let\setuplistinghook = \linenumberedlisting'. The line numbers are stored in the count register `\lineno' while the file is being read. You can redefine the macro `\printlistinglineno' to change how they are printed. You can produce in-line verbatim text in your document with `\verbatim'. End the text with `|endverbatim'. If you need a `|' in the text, double it. If the first character of the verbatim text is a space, use `| '. (`| ' will work elsewhere in the argument, too, but isn't necessary.) For example: \verbatim| ||\#%&!|endverbatim produces ` |\#%&!'. Line breaks and spaces in the verbatim text are preserved. You can change the verbatim escape character from the default `|' with `\verbatimescapechar CHAR'; for example, this changes it to `@'. \verbatimescapechar \@ The backslash is not necessary in some cases, but is in others, depending on the catcode of the character. The argument to `\verbatimescapechar' is used as `\catcode `CHAR', so the exact rules follow that for `\catcode'. Because `\verbatim' must change the category code of special characters, calling inside a macro definition of your own does not work properly. For example: \def\mymacro{\verbatim &#%|endverbatim}% Doesn't work! To accomplish this, you must change the category codes yourself before making the macro definition. Perhaps `\uncatcodespecials' will help you (*note Category codes::.). File: eplain.info, Node: Contents, Next: Cross-references, Prev: Verbatim listing, Up: User definitions Contents ======== Producing a table of contents that is both useful and aesthetic is one of the most difficult design problems in any work. Naturally, Eplain does not pretend to solve the design problem. Collecting the raw data for a table of contents, however, is much the same across documents. Eplain uses an auxiliary file with extension `.toc' (and the same root name as your document) to save the information. To write an entry for the table of contents, you say `\writetocentry{PART}{TEXT}', where PART is the type of part this entry is, e.g., `chapter', and TEXT is the text of the title. `\writetocentry' puts an entry into the .toc file that looks like `\tocPARTentry{TEXT}{PAGE NUMBER}'. The TEXT is written unexpanded. A related command, `\writenumberedtocentry', takes one additional argument, the first token of which is expanded at the point of the `\writenumberedtocentry', but the rest of the argument is not expanded. The usual application is when the parts of the document are numbered. On the other hand, the one-level expansion allows you to use the argument for other things as well (author's names in a proceedings, say), and not have accents or other control sequences expanded. The downside is that if you *want* full expansion of the third argument, you don't get it--you must expand it yourself, before you call `\writenumberedtocentry'. For example: \writenumberedtocentry{chapter}{A $\sin$ wave}{\the\chapno} \writetocentry{section}{A section title} Supposing `\the\chapno' expanded to `3' and that the `\write''s occurred on pages eight and nine, respectively, the above writes the following to the .toc file: \tocchapterentry{A $\sin$ wave}{3}{8} \tocsectionentry{A section title}{9} You read the .toc file with the command `\readtocfile'. Naturally, whatever `\toc... entry' commands that were written to the file must be defined when `\readtocfile' is invoked. Eplain has minimal definitions for `\tocchapterentry', `\tocsectionentry', and `\tocsubsectionentry', just to prevent undefined control sequence errors in common cases. They aren't suitable for anything but preliminary proofs. After reading the .toc file, `\readtocfile' opens the file for writing, thereby deleting the information from the previous run. You should therefore arrange that `\readtocfile' be called *before* the first call to a `\writetoc...' macro. On the other hand, if you don't want to rewrite the .toc file, perhaps because you are only running TeX on part of your manuscript, you can set `\rewritetocfilefalse'. By default, the `.toc' file has the root `\jobname'. If your document has more than one contents--for example, if it is a collection of papers, some of which have their own contents--you can tell Eplain to use a different root name by defining the control sequence `\tocfilebasename'. In addition to the usual table of contents, you may want to have a list of figures, list of tables, or other such contents-like list. You can do this with `\definecontentsfile{ABBREV}'. All of the above commands are actually a special case that Eplain predefines with \definecontentsfile{toc} The ABBREV is used both for the file extension and in the control sequence names. File: eplain.info, Node: Cross-references, Next: Page references, Prev: Contents, Up: User definitions Cross-references ================ It is often useful to refer the reader to other parts of your document; but putting literal page, section, equation, or whatever numbers in the text is certainly a bad thing. Eplain therefore provides commands for symbolic cross-references. It uses an auxiliary file with extension .aux (and the same root name as your document) to keep track of the information. Therefore, it takes two passes to get the cross-references right--one to write them out, and one to read them in. Eplain automatically reads the .aux file at the first reference; after reading it, Eplain reopens it for writing. You can control whether or not Eplain warns you about undefined labels. *Note Citations::. Labels in Eplain's cross-reference commands can use characters of category code eleven (letter), twelve (other), ten (space), three (math shift), four (alignment tab), seven (superscript), or eight (subscript). For example, `(a1 $&^_' is a valid label (assuming the category codes of plain TeX), but `%#\{' has no valid characters. You can also do symbolic cross-references for bibliographic citations and list items. *Note Citations::, and *Note Lists::. * Menu: * Defining generic references:: * Using generic references:: File: eplain.info, Node: Defining generic references, Next: Using generic references, Up: Cross-references Defining generic references --------------------------- Eplain provides the command `\definexref' for general cross-references. It takes three arguments: the name of the label (see section above for valid label names), the value of the label (which can be anything), and the "class" of the reference--whether it's a section, or theorem, or what. For example: \definexref{sec-intro}{3.1}{section} Of course, the label value is usually generated by another macro using TeX count registers or some such. `\definexref' doesn't actually define LABEL; instead, it writes out the definition to the .aux file, where Eplain will read it on the next TeX run. The CLASS argument is used by the `\ref' and `\refs' commands. See the next section. File: eplain.info, Node: Using generic references, Prev: Defining generic references, Up: Cross-references Using generic references ------------------------ To retrieve the value of the label defined via `\definexref' (see the previous section), Eplain provides the following macros: `\refn{LABEL}' `\xrefn{LABEL}' `\refn' and `\xrefn' (they are synonyms) produce the bare definition of LABEL. If LABEL isn't defined, issue a warning, and produce LABEL itself instead, in typewriter. (The warning isn't given if `\xrefwarningfalse'.) `\ref{LABEL}' Given the class C for LABEL (see the description of `\definexref' in the previous section), expand the control sequence `\C word' (if it's defined) followed by a tie. Then call `\refn' on LABEL. (Example below.) `\refs{LABEL}' Like `\ref', but append the letter `s' to the `\...word'. The purpose of the `\...word' macro is to produce the word `Section' or `Figure' or whatever that usually precedes the actual reference number. Here is an example: \def\sectionword{Section} \definexref{sec-intro}{3.1}{section} \definexref{sec-next}{3.2}{section} See \refs{sec-intro} and \refn{sec-next} ... This produces `See Sections 3.1 and 3.2 ...' File: eplain.info, Node: Page references, Next: Indexing, Prev: Cross-references, Up: User definitions Page references =============== Eplain provides two commands for handling references to page numbers, one for definition and one for use. `\xrdef{LABEL}' Define LABEL to be the current page number. This produces no printed output, and ignores following spaces. `\xref{LABEL}' Produce the text `p. PAGE-NUMBER', which is the usual form for cross-references. The PAGE-NUMBER is actually LABEL's definition; if LABEL isn't defined, the text of the label itself is printed. * Menu: * Equation references:: File: eplain.info, Node: Equation references, Up: Page references Equation references ------------------- Instead of referring to pages, it's most useful if equation labels refer to equation numbers. Therefore, Eplain reserves a `\count' register, `\eqnumber', for the current equation number, and increments it at each numbered equation. Here are the commands to define equation labels and then refer to them: `\eqdef{LABEL}' This defines LABEL to be the current value of `\eqnumber', and, if the current context is not inner, then produces a `\eqno' command. (The condition makes it possible to use `\eqdef' in an `\eqalignno' construction, for example.) The text of the equation number is produced using `\eqprint'. *Note Formatting equation references::. If LABEL is empty, you still get an equation number (although naturally you can't reliably refer to it). This is useful if you want to put numbers on all equations in your document, and you don't want to think up unique labels. `\eqdefn{LABEL}' This is like `\eqdef', except it always omits the `\eqno' command. It can therefore be used in places where `\eqdef' can't; for example, in a non-displayed equation. The text of the equation number is not produced, so you can also use it in the (admittedly unusual) circumstance when you want to define an equation label but not print that label. `\eqref{LABEL}' This produces a formatted reference to LABEL. If LABEL is undefined (perhaps because it is a forward reference), it just produces the text of the label itself. Otherwise, it calls `\eqprint'. `\eqrefn{LABEL}' This produces the cross-reference text for LABEL. That is, it is like `\eqref', except it doesn't call `\eqprint'. Equation labels can contain the same characters that are valid in general cross-references. * Menu: * Formatting equation references:: * Subequation references:: File: eplain.info, Node: Formatting equation references, Next: Subequation references, Up: Equation references Formatting equation references .............................. Both defining an equation label and referring to it should usually produce output. This output is produced with the `\eqprint' macro, which takes one argument, the equation number being defined or referred to. By default, this just produces `(NUMBER)', where NUMBER is the equation number. To produce the equation number in a different font, or with different surrounding symbols, or whatever, you can redefine `\eqprint'. For example, the following definition would print all equation numbers in italics. (The extra braces define a group, to keep the font change from affecting surrounding text.) \def\eqprint#1{{\it (#1)}} In addition to changing the formatting of equation numbers, you might to add more structure to the equation number; for example, you might want to include the chapter number, to get equation numbers like `(1.2)'. To achieve this, you redefine `\eqconstruct'. For example: \def\eqconstruct#1{\the\chapternumber.#1} (If you are keeping the chapter number in a count register named `\chapternumber', naturally.) The reason for having both `\eqconstruct' and `\eqprint' may not be immediately apparent. The difference is that `\eqconstruct' affects the text that cross-reference label is defined to be, while `\eqprint' affects only what is typeset on the page. The example just below might help. Usually, you want equation labels to refer to equation numbers. But sometimes you might want a more complicated text. For example, you might have an equation `(1)', and then have a variation several pages later which you want to refer to as `(1*)'. Therefore, Eplain allows you to give an optional argument (i.e., arbitrary text in square brackets) before the cross-reference label to \eqdef. Then, when you refer to the equation, that text is produced. Here's how to get the example just mentioned: $$...\eqdef{a-eq}$$ ... $$...\eqdef[\eqrefn{a-eq}*]{a-eq-var}$$ In \eqref{a-eq-var}, we expand on \eqref{a-eq}, ... We use `\eqrefn' in the cross-reference text, not `\eqref', so that `\eqprint' is called only once. File: eplain.info, Node: Subequation references, Prev: Formatting equation references, Up: Equation references Subequation references ...................... Eplain also provides for one level of substructure for equations. That is, you might want to define a related group of equations with numbers like `2.1' and `2.2', and then be able to refer to the group as a whole: "... in the system of equations (2)...". The commands to do this are `\eqsubdef' and `\eqsubdefn'. They take one LABEL argument like their counterparts above, and generally behave in the same way. The difference is in how they construct the equation number: instead of using just `\eqnumber', they also use another counter, `\subeqnumber'. This counter is advanced by one at every `\eqsubdef' or `\eqsubdefn', and reset to zero at every `\eqdef' or `\eqdefn'. You use `\eqref' to refer to subequations as well as main equations. To put the two together to construct the text that the label will produce, they use a macro `\eqsubreftext'. This macros takes two arguments, the "main" equation number (which, because the equation label can be defined as arbitrary text, as described in the previous section, might be anything at all) and the "sub" equation number (which is always just a number). Eplain's default definition just puts a period between them: \def\eqsubreftext#1#2{#1.#2}% You can redefine `\eqsubreftext' to print however you like. For example, this definition makes the labels print as `2a', `2b', and so \newcount\subref \def\eqsubreftext#1#2{% \subref = #2 % The space stops a <number>. \advance\subref by 96 % `a' is character code 97. #1\char\subref } Sadly, we must define a new count register, `\subref', instead of using the scratch count register `\count255', because `#1' might include other macro calls which use `\count255'.